<!--This file created 4:13 PM  4/13/97 by Claris Home Page version 2.0-->
<HTML>
<HEAD>
   <TITLE>Overview of GEF v0.6</TITLE>
</HEAD>
<BODY BGCOLOR="FFFFFF">

<H1>Overview of GEF v0.6</H1>

<p>This file gives a brief overview of the structure and style of the
code in the UCI Graph Editing Framework.

<p>This file was prepared on 5/30/97, revised 4/18/98.</p>

<H2><FONT COLOR="#006600">Contents:</FONT></H2>
<UL>
<LI>	S0.  <A HREF="#Copyright">Copyright</A>
<LI>	S1.  <A HREF="#Vision">Vision</A>.
<LI>	S2.  <A HREF="#OverallArchitecture">Overall Architecture</A>
<LI>	S3.  <A HREF="#ClassClusters ">Class Clusters</A>
<LI>	S4.  <A HREF="#CodingStyle">Coding Style</A>
<LI>	S5.  <A HREF="#ContactInfo">Contact info</A>
</UL>

<HR>
<A NAME="Copyright">
<H2><FONT COLOR="#006600">Section 0.  Copyright</FONT></H2>
<FONT SIZE=2>
<p>Copyright (c) 1995, 1996 Regents of the University of California.
All rights reserved.

<p>This software was developed by the Arcadia project
at the University of California, Irvine.

<p> <FONT SIZE=1>
 Copyright (c) 1996-98 The Regents of the University of California. All
 Rights Reserved. Permission to use, copy, modify, and distribute this
 software and its documentation for educational, research and non-profit
 purposes, without fee, and without a written agreement is hereby granted,
 provided that the above copyright notice and this paragraph appear in all
 copies. Permission to incorporate this software into commercial products may
 be obtained by contacting the University of California. David F. Redmiles
 Department of Information and Computer Science (ICS) University of
 California Irvine, California 92697-3425 Phone: 714-824-3823. This software
 program and documentation are copyrighted by The Regents of the University
 of California. The software program and documentation are supplied "as is",
 without any accompanying services from The Regents. The Regents do not
 warrant that the operation of the program will be uninterrupted or
 error-free. The end-user understands that the program was developed for
 research purposes and is advised not to rely exclusively on the program for
 any reason. IN NO EVENT SHALL THE UNIVERSITY OF CALIFORNIA BE LIABLE TO ANY
 PARTY FOR DIRECT, INDIRECT, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES,
 INCLUDING LOST PROFITS, ARISING OUT OF THE USE OF THIS SOFTWARE AND ITS
 DOCUMENTATION, EVEN IF THE UNIVERSITY OF CALIFORNIA HAS BEEN ADVISED OF THE
 POSSIBILITY OF SUCH DAMAGE. THE UNIVERSITY OF CALIFORNIA SPECIFICALLY
 DISCLAIMS ANY WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
 WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE
 SOFTWARE PROVIDED HEREUNDER IS ON AN "AS IS" BASIS, AND THE UNIVERSITY OF
 CALIFORNIA HAS NO OBLIGATIONS TO PROVIDE MAINTENANCE, SUPPORT, UPDATES,
 ENHANCEMENTS, OR MODIFICATIONS.
</FONT>



<HR>
<A NAME="Vision">
<H2><FONT COLOR="#006600">Section 1.  Vision</FONT></H2>

<p>Basically, I want to have a nice, stable graph editing and
MacDraw-style graphics editing framework.  I need that as a starting
point for a tool I am building for my Ph.D.  research, and I think that
others need a framework like that as well.

<p>Some of the goals of the framework are to support these features:
<UL>
<LI> Full editing of unstructured graphics, so that it is possible to
  make nice looking diagrams.
<LI> Ease of use, so that people who are browsing the web can figure out
  what to do with my demos without having to read a lot of
  documentation.
<LI> Connected graph editing, because that is needed in my application.
<LI> Multiple, coordinated views, so that complex connected graphs can be
  visualized in different ways.
<LI> Easy integration with application specific code, so that people can
  put a graphical front end on their applications without rewriting
  everything around my framework.
<LI> Simple enough for college students to learn and use in 10 weeks.
</UL>

<p>I think it would be really interesting to organanize a "virtual
software development team" over the internet so that: (1) I don't have
to do all the coding myself, (2) the final framework is tempered by
actual application, (3) we all get experience in distributed
development, (4) I get in contact with professional developers for
future collaboration, user testing, and even job offers.  As virtual
team leader I promise to integrate changes, run the project web page,
suggest projects, and avoid duplication of effort.  I am especially
interested in instructors at universities who want to use this
software as material for project classes (see the history section of
the GEF home page).  

<p>The framework should promote the creation of good demos for the
www.  That means that they should download quickly, look nice, have
enough features to look professional, and let the user get to the point
of the demo without fighting with a difficult interface.

<p>More importantly, the framework should promote the creation of good
applications.  It should have a rich set of basic features.  It should
be easily customized to a given application.  It should look nice and
be easy to use (or at least be like other applications).



<HR>
<A NAME="OverallArchitecture">
<H2><FONT COLOR="#006600">Section 2.  Overall Architecture</FONT></H2>

<p>There are two main levels in the Graph Editing Framework (GEF)
representation: (1) the net level, and (2) the diagram level.  The net
level holds nodes which are logical objects that may have application
specific data and behavior.  The diagram level made up of
<TT>Fig</TT>s for structured and unstructured graphics that
visually depict the net and various annotations.

<p>I expect that people will use the framework by extending it by adding
new classes.  In Java the class is the most important unit of syntax,
version control, code distribution, and dynamic loading.  I have tried
design the framework so that people never have to modify existing
code.  I don't know if that is not the case yet, but hopefully it will
be.

<p>The graph editor (in class <TT>Editor</TT>) is just a shell that dispatches
control to various other objects that do the actual drawing and
processing of input events.  The supporting classes are in several
clusters described below.



<HR>
<A NAME="ClassClusters">
<H2><FONT COLOR="#006600">Section 3.  Class Clusters</FONT></H2>
<UL>

<LI> <TT>Editor</TT> is the most central class of the system. There is
one instance of of Editor for every diagram that is displayed on the
screen.  <TT>Editor</TT> acts as a shell: <TT>Editor</TT> does not
handle input events, redraw the screen, determine what item the user
clicked on, or modify the diagram data structure itself.  Instead it
passes events and messages to supporting objects from the other clusters.

<LI> <TT>Cmd</TT>s are classes that define a <TT>doIt()</TT> method
that performs some action in the <TT>Editor</TT>.  For example
<TT>CmdReorder</TT> handles the menu items 'Send to back', 'Bring
to front', etc. Ideally, an action should be used for any modification
or command that the user might want to undo, include in a macro, or
get help about.

<LI> <TT>Mode</TT>s are modes of operation for the <TT>Editor</TT>.
They can potentially be long term modes, for example preview mode
vs. ray tracing mode.  But so far I have only done short term modes
for selection, modification, and creation of new objects.  For
example, when you drag an object around the <TT>Editor</TT> is in
<TT>ModeModify</TT>, but when you release the mouse button the
<TT>Editor</TT> returns to <TT>ModeSelect</TT>.

<LI> <TT>Guide</TT>s are objects that help the user make clean looking
diagrams by constraining mouse coordinates. For example,
<TT>GuideGrid</TT> implements grid snap. 

<LI> <TT>Fig</TT>s are drawable objects that can be shown
and manipulated in the <TT>Editor</TT>.  <TT>Fig</TT>s (short for
Figures) are basic drawing elements such as lines and
rectangles. <TT>FigGroup</TT> is the class for groups of <TT>Fig</TT>s.
<TT>Perspective</TT>s are compound drawing elements that represent
objects in the underlying net level representation.

<LI> <TT>Layer</TT>s serve both to group <TT>Fig</TT>s into
transparent overlays (as in many high end drawing packages) and to
manage redraw order and find the objects under a given mouse
point. That is to say, they may serve as both display lists, and pick
lists. Some <TT>Layer</TT>s compute their visualization rather than
storing a list of <TT>Fig</TT>s, for example
<TT>LayerGrid</TT>.

<LI> <TT>Selection</TT>s are objects used by the <TT>Editor</TT> when
the user selects a <TT>Fig</TT>.  <TT>Selection</TT>s are
responsible for drawing handles and handling dragging on handles. 

 </UL>


<HR>
<A NAME="CodingStyle">
<H2><FONT COLOR="#006600">Section 4.  Coding Style</FONT></H2>

<p>I am including this section (1) so that anyone who modifies this code
can work toward the same style that I am tring to achieve throughout
the source code, (2) as a form of documentation so that you know what
you are reading.  Unfortuantly, the code does not consistantly follow
all of these rules yet, but it is close.

<UL>

<LI>  Each file starts with some header info: file, classes in this
file, original author's email address, and version control info.

<LI> I am using the <TT>import ...*;</TT> command to keep the code
short.  I perfer to let name conflicts arrise so that I can catch
them, rather than always use explicit package.class names and end up
with code that cannot be changed to the package-name-only
style. (Note: This means that if you make a zip file for use in your
<TT>CLASSPATH</TT>, you must use a version of the zip tool that
includes directory entries.)

<LI> All instance variables are protected and their names begin with an
underscore.  If the variable should be accessible then add public or
protected accessor methods with the same name as the variable without
the underscore with "<TT>get</TT>" or "<TT>set</TT>" prepended. For
example: <TT>_lineWidth</TT>, <TT>setLineWidth()</TT>, and
<TT>getLineWidth()</TT>.

<LI> In general, write short code.  If a method will fit
comfortably on one line, then put it on one line.

<LI>  Use javadoc for each class, instance variable, and method.  In
general do not put comments in the body of a method.  If you are doing
something complex enough to need a comment, consider breaking it out
into its own commented method.

<LI>  Indicate places of future modifications with
"<TT>// Needs-More-Work: reason</TT>"

<LI> Name all classes with an initial uppercase letter, and all
variables and methods with a lowercase one.  I use the
allTogetherWithCaps naming style.  Name static variables with an
underscore and an inital capital letter, e.g.,
<TT>_PossibleLanguages</TT>.  Name constants with all upper case and
underscores, e.g., <TT>GRIP_MARGIN</TT>. 

<LI> To emphasize clusters of classes I am using what I call the
binomial naming style (I am sure others have thought of this also):
The root class of the cluster has a short name (e.g., <TT>Layer</TT>),
other members of the cluster use that name as a prefix (e.g.,
<TT>LayerGrid</TT>).  This makes many of the class name longer than
they might be normally (e.g., <TT>Grid</TT> would be shorter).  But
this provides a lot of context without having to look at a class
inheritance diagram.  It is also very nice when you have to look at an
alphabetical list of classes.  I try to name class clusters so that
they are not lexigraphically close others (e.g., the Net cluster used
to be named Model, but that lexigraphically overlapped the Mode
cluster).

<LI> The file <A HREF="features.html"> <TT>uci/docs/features.html
</TT></A> lists out all features that are supported by GEF.  This is
the closest thing that GEF has to a requirements document. 

<LI> There is a list of bugs in <A HREF="bugs.html"><TT>
uci/doc/bugs.html</TT></A>.  Each bug is marked with an HTML archor
that names the bug.  Javadocs for code that contains a bug, fixes a
bug, or works around a bug should have a hyperlink back to the proper
bug anchor(s).

<LI>  When in doubt, follow Sun java style conventions.

</UL>


<HR>
<A NAME="ContactInfo">
<H2><FONT COLOR="#006600">Section 5.  Contact Information</FONT></H2>

Please direct any questions or comments to <A
HREF="mailto:dev&#064;gef.tigris.org"><TT>dev&#064;gef.tigris.org</TT></A>.

The Graph Editing Framework home page is 
<A HREF="http://gef.tigris.org">http://gef.tigris.org/</A>.

The mailing list <TT>gef-users</TT> is for people using GEF on their
own projects.  Typical messges are questions, suggestions, and
announcements of new versions.  Message volume on this list is quite
low, and I never give out information about who is on the list.  See
the GEF home page for info on adding yourself to the mailing list.

<hr>
<a href="index.html">GEF v0.6 docs</a> |
<a href="../../"> GEF home page</a>

</BODY>
</HTML>
